The Org Manual

Org Mode Manual

This manual is for Org version 7.4.

Copyright © 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF's Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

• Introduction: Getting started
• Document Structure: A tree works like your brain
• Tables: Pure magic for quick formatting
• Hyperlinks: Notes in context
• TODO Items: Every tree branch can be a TODO item
• Tags: Tagging headlines and matching sets of tags
• Properties and Columns: Storing information about an entry
• Dates and Times: Making items useful for planning
• Capture - Refile - Archive: The ins and outs for projects
• Agenda Views: Collecting information into views
• Markup: Prepare text for rich export
• Exporting: Sharing and publishing of notes
• Publishing: Create a web site of linked Org files
• Working With Source Code: Export, evaluate, and tangle code blocks
• Miscellaneous: All the rest which did not fit elsewhere
• Hacking: How to hack your way around
• MobileOrg: Viewing and capture on a mobile device
• History and Acknowledgments: How Org came into being
• Main Index: An index of Org's concepts and features
• Key Index: Key bindings and where they are described
• Command and Function Index: Command names and some internal functions
• Variable Index: Variables mentioned in the manual

--- The Detailed Node Listing ---

Introduction

• Summary: Brief summary of what Org does
• Installation: How to install a downloaded version of Org
• Activation: How to activate Org for certain buffers
• Feedback: Bug reports, ideas, patches etc.
• Conventions: Type-setting conventions in the manual

Document structure

• Outlines: Org is based on Outline mode
• Headlines: How to typeset Org tree headlines
• Visibility cycling: Show and hide, much simplified
• Motion: Jumping to other headlines
• Structure editing: Changing sequence and level of headlines
• Sparse trees: Matches embedded in context
• Plain lists: Additional structure within an entry
• Drawers: Tucking stuff away
• Blocks: Folding blocks
• Footnotes: How footnotes are defined in Org's syntax
• Orgstruct mode: Structure editing outside Org

Tables

• Built-in table editor: Simple tables
• Column width and alignment: Overrule the automatic settings
• Column groups: Grouping to trigger vertical lines
• Orgtbl mode: The table editor as minor mode
• The spreadsheet: The table editor has spreadsheet capabilities
• Org-Plot: Plotting from org tables

The spreadsheet

• References: How to refer to another field or range
• Formula syntax for Calc: Using Calc to compute stuff
• Formula syntax for Lisp: Writing formulas in Emacs Lisp
• Field formulas: Formulas valid for a single field
• Column formulas: Formulas valid for an entire column
• Editing and debugging formulas: Fixing formulas
• Updating the table: Recomputing all dependent fields
• Advanced features: Field names, parameters and automatic recalc

Hyperlinks

• Link format: How links in Org are formatted
• Internal links: Links to other places in the current file
• External links: URL-like links to the world
• Handling links: Creating, inserting and following
• Using links outside Org: Linking from my C source code?
• Link abbreviations: Shortcuts for writing complex links
• Search options: Linking to a specific location
• Custom searches: When the default search is not enough

Internal links

• Radio targets: Make targets trigger links in plain text

TODO items

• TODO basics: Marking and displaying TODO entries
• TODO extensions: Workflow and assignments
• Progress logging: Dates and notes for progress
• Priorities: Some things are more important than others
• Breaking down tasks: Splitting a task into manageable pieces
• Checkboxes: Tick-off lists

Extended use of TODO keywords

• Workflow states: From TODO to DONE in steps
• TODO types: I do this, Fred does the rest
• Multiple sets in one file: Mixing it all, and still finding your way
• Fast access to TODO states: Single letter selection of a state
• Per-file keywords: Different files, different requirements
• Faces for TODO keywords: Highlighting states
• TODO dependencies: When one task needs to wait for others

Progress logging

• Closing items: When was this entry marked DONE?
• Tracking TODO state changes: When did the status change?
• Tracking your habits: How consistent have you been?

Tags

• Tag inheritance: Tags use the tree structure of the outline
• Setting tags: How to assign tags to a headline
• Tag searches: Searching for combinations of tags

Properties and columns

• Property syntax: How properties are spelled out
• Special properties: Access to other Org-mode features
• Property searches: Matching property values
• Property inheritance: Passing values down the tree
• Column view: Tabular viewing and editing
• Property API: Properties for Lisp programmers

Column view

• Defining columns: The COLUMNS format property
• Using column view: How to create and use column view
• Capturing column view: A dynamic block for column view

Defining columns

• Scope of column definitions: Where defined, where valid?
• Column attributes: Appearance and content of a column

Dates and times

• Timestamps: Assigning a time to a tree entry
• Creating timestamps: Commands which insert timestamps
• Deadlines and scheduling: Planning your work
• Clocking work time: Tracking how long you spend on a task
• Effort estimates: Planning work effort in advance
• Relative timer: Notes with a running timer
• Countdown timer: Starting a countdown timer for a task

Creating timestamps

• The date/time prompt: How Org-mode helps you entering date and time
• Custom time format: Making dates look different

Deadlines and scheduling

• Inserting deadline/schedule: Planning items
• Repeated tasks: Items that show up again and again

Clocking work time

• Clocking commands: Starting and stopping a clock
• The clock table: Detailed reports
• Resolving idle time: Resolving time when you've been idle

Capture - Refile - Archive

• Capture: Capturing new stuff
• Attachments: Add files to tasks
• RSS Feeds: Getting input from RSS feeds
• Protocols: External (e.g. Browser) access to Emacs and Org
• Refiling notes: Moving a tree from one place to another
• Archiving: What to do with finished projects

Capture

• Setting up capture: Where notes will be stored
• Using capture: Commands to invoke and terminate capture
• Capture templates: Define the outline of different note types

Capture templates

• Template elements: What is needed for a complete template entry
• Template expansion: Filling in information about time and context

Archiving

• Moving subtrees: Moving a tree to an archive file
• Internal archiving: Switch off a tree but keep it in the file

Agenda views

• Agenda files: Files being searched for agenda information
• Agenda dispatcher: Keyboard access to agenda views
• Built-in agenda views: What is available out of the box?
• Presentation and sorting: How agenda items are prepared for display
• Agenda commands: Remote editing of Org trees
• Custom agenda views: Defining special searches and views
• Exporting Agenda Views: Writing a view to a file
• Agenda column view: Using column view for collected entries

The built-in agenda views

• Weekly/daily agenda: The calendar page with current tasks
• Global TODO list: All unfinished action items
• Matching tags and properties: Structured information with fine-tuned search
• Timeline: Time-sorted view for single file
• Search view: Find entries by searching for text
• Stuck projects: Find projects you need to review

Presentation and sorting

• Categories: Not all tasks are equal
• Time-of-day specifications: How the agenda knows the time
• Sorting of agenda items: The order of things

Custom agenda views

• Storing searches: Type once, use often
• Block agenda: All the stuff you need in a single buffer
• Setting Options: Changing the rules

Markup for rich export

• Structural markup elements: The basic structure as seen by the exporter
• Images and tables: Tables and Images will be included
• Literal examples: Source code examples with special formatting
• Include files: Include additional files into a document
• Index entries: Making an index
• Macro replacement: Use macros to create complex output
• Embedded LaTeX: LaTeX can be freely used inside Org documents

Structural markup elements

• Document title: Where the title is taken from
• Headings and sections: The document structure as seen by the exporter
• Table of contents: The if and where of the table of contents
• Initial text: Text before the first heading?
• Lists: Lists
• Paragraphs: Paragraphs
• Footnote markup: Footnotes
• Emphasis and monospace: Bold, italic, etc.
• Horizontal rules: Make a line
• Comment lines: What will *not* be exported

Embedded LaTeX

• Special symbols: Greek letters and other symbols
• Subscripts and superscripts: Simple syntax for raising/lowering text
• LaTeX fragments: Complex formulas made easy
• Previewing LaTeX fragments: What will this snippet look like?
• CDLaTeX mode: Speed up entering of formulas

Exporting

• Selective export: Using tags to select and exclude trees
• Export options: Per-file export settings
• The export dispatcher: How to access exporter commands
• ASCII/Latin-1/UTF-8 export: Exporting to flat files with encoding
• HTML export: Exporting to HTML
• LaTeX and PDF export: Exporting to LaTeX, and processing to PDF
• DocBook export: Exporting to DocBook
• TaskJuggler export: Exporting to TaskJuggler
• Freemind export: Exporting to Freemind mind maps
• XOXO export: Exporting to XOXO
• iCalendar export: Exporting in iCalendar format

HTML export

• HTML Export commands: How to invoke HTML export
• Quoting HTML tags: Using direct HTML in Org-mode
• Links in HTML export: How links will be interpreted and formatted
• Tables in HTML export: How to modify the formatting of tables
• Images in HTML export: How to insert figures into HTML output
• Math formatting in HTML export: Beautiful math also on the web
• Text areas in HTML export: An alternative way to show an example
• CSS support: Changing the appearance of the output
• JavaScript support: Info and Folding in a web browser

LaTeX and PDF export

• LaTeX/PDF export commands: Which key invokes which commands
• Header and sectioning: Setting up the export file structure
• Quoting LaTeX code: Incorporating literal LaTeX code
• Tables in LaTeX export: Options for exporting tables to LaTeX
• Images in LaTeX export: How to insert figures into LaTeX output
• Beamer class export: Turning the file into a presentation

DocBook export

• DocBook export commands: How to invoke DocBook export
• Quoting DocBook code: Incorporating DocBook code in Org files
• Recursive sections: Recursive sections in DocBook
• Tables in DocBook export: Tables are exported as HTML tables
• Images in DocBook export: How to insert figures into DocBook output
• Special characters: How to handle special characters

Publishing

• Configuration: Defining projects
• Uploading files: How to get files up on the server
• Sample configuration: Example projects
• Triggering publication: Publication commands

Configuration

• Project alist: The central configuration variable
• Sources and destinations: From here to there
• Selecting files: What files are part of the project?
• Publishing action: Setting the function doing the publishing
• Publishing options: Tweaking HTML export
• Publishing links: Which links keep working after publishing?
• Sitemap: Generating a list of all pages
• Generating an index: An index that reaches across pages

Sample configuration

• Simple example: One-component publishing
• Complex example: A multi-component publishing example

Working with source code

• Structure of code blocks: Code block syntax described
• Editing source code: Language major-mode editing
• Exporting code blocks: Export contents and/or results
• Extracting source code: Create pure source code files
• Evaluating code blocks: Place results of evaluation in the Org-mode buffer
• Library of Babel: Use and contribute to a library of useful code blocks
• Languages: List of supported code block languages
• Header arguments: Configure code block functionality
• Results of evaluation: How evaluation results are handled
• Noweb reference syntax: Literate programming in Org-mode
• Key bindings and useful functions: Work quickly with code blocks
• Batch execution: Call functions from the command line

Header arguments

• Using header arguments: Different ways to set header arguments
• Specific header arguments: List of header arguments

Using header arguments

• System-wide header arguments: Set global default values
• Language-specific header arguments: Set default values by language
• Buffer-wide header arguments: Set default values for a specific buffer
• Header arguments in Org-mode properties: Set default values for a buffer or heading
• Code block specific header arguments: The most common way to set values
• Header arguments in function calls: The most specific level

Specific header arguments

• var: Pass arguments to code blocks
• results: Specify the type of results and how they will be collected and handled
• file: Specify a path for file output
• dir: Specify the default (possibly remote) directory for code block execution
• exports: Export code and/or results
• tangle: Toggle tangling and specify file name
• comments: Toggle insertion of comments in tangled code files
• no-expand: Turn off variable assignment and noweb expansion during tangling
• session: Preserve the state of code evaluation
• noweb: Toggle expansion of noweb references
• cache: Avoid re-evaluating unchanged code blocks
• hlines: Handle horizontal lines in tables
• colnames: Handle column names in tables
• rownames: Handle row names in tables
• shebang: Make tangled files executable
• eval: Limit evaluation of specific code blocks

Miscellaneous

• Completion: M-TAB knows what you need
• Easy Templates: Quick insertion of structural elements
• Speed keys: Electric commands at the beginning of a headline
• Code evaluation security: Org mode files evaluate inline code
• Customization: Adapting Org to your taste
• In-buffer settings: Overview of the #+KEYWORDS
• The very busy C-c C-c key: When in doubt, press C-c C-c
• Clean view: Getting rid of leading stars in the outline
• TTY keys: Using Org on a tty
• Interaction: Other Emacs packages

Interaction with other packages

• Cooperation: Packages Org cooperates with
• Conflicts: Packages that lead to conflicts

Hacking

• Hooks: Who to reach into Org's internals
• Add-on packages: Available extensions
• Adding hyperlink types: New custom link types
• Context-sensitive commands: How to add functionality to such commands
• Tables in arbitrary syntax: Orgtbl for LaTeX and other programs
• Dynamic blocks: Automatically filled blocks
• Special agenda views: Customized views
• Extracting agenda information: Postprocessing of agenda information
• Using the property API: Writing programs that use entry properties
• Using the mapping API: Mapping over all or selected entries

Tables and lists in arbitrary syntax

• Radio tables: Sending and receiving radio tables
• A LaTeX example: Step by step, almost a tutorial
• Translator functions: Copy and modify
• Radio lists: Doing the same for lists

MobileOrg

• Setting up the staging area: Where to interact with the mobile device
• Pushing to MobileOrg: Uploading Org files and agendas
• Pulling from MobileOrg: Integrating captured and flagged items